x-phonecontact-s 通讯录

添加与选择手机通讯录联系人。参数对齐微信 wx.addPhoneContact / wx.chooseContact，回调使用 DCloud success / fail / complete。对外方法名为 xAddPhoneContact、xChooseContact，类型统一加 X 前缀，避免和官方同名冲突。

App / 鸿蒙拉起系统联系人界面，由用户确认后写入或选择；不在后台静默改通讯录。

兼容性

Harmony	iOS	Android	WEB	微信小程序
支持	支持	支持	选择联系人（Chrome Contact Picker）	支持

调用

import {
  xAddPhoneContact,
  xChooseContact,
  XAddPhoneContactOptions,
  XChooseContactOptions,
  XChooseContactResult,
  XPhoneContactFailInfo
} from "@/uni_modules/x-phonecontact-s"

xAddPhoneContact({
  firstName: "三",
  lastName: "张",
  mobilePhoneNumber: "13800138000",
  organization: "示例公司",
  success: (res) => {
    console.log(res.errMsg)
  },
  fail: (err : XPhoneContactFailInfo) => {
    console.log(err.errCode, err.errMsg)
  }
} as XAddPhoneContactOptions)

xChooseContact({
  success: (res : XChooseContactResult) => {
    console.log(res.displayName, res.phoneNumber, res.phoneNumberList)
  }
} as XChooseContactOptions)

方法

名称	说明
xAddPhoneContact	预填联系人并拉起系统新建/写入界面
xChooseContact	拉起手机通讯录，选择联系人

选择结果

XChooseContactResult

字段	说明
displayName	联系人姓名
phoneNumber	当前选中的手机号
phoneNumberList	该联系人的全部手机号
errMsg	xChooseContact:ok

错误码

码	含义
1001	系统错误
1002	参数错误（微信写入时 firstName 必填）
1004	权限被拒绝
1005	正在进行其他通讯录操作
1006	用户取消
1008	当前平台不支持此功能

平台差异

1. 微信走官方 wx.addPhoneContact / wx.chooseContact。phoneNumberList 在部分安卓微信上可能是字符串，插件会归一成 string[]。
2. Android 写入走系统 ACTION_INSERT（直接新建联系人页），选择走 ACTION_PICK 并优先绑定系统通讯录，不申请读写通讯录权限；查询全部号码失败时至少返回当前选中号。
3. iOS 使用 CNContactViewController / CNContactPickerViewController。
4. HarmonyOS 写入走系统通讯录 startAbility（page_flag_save_contact），选择走 selectContacts，不申请受限的读写通讯录权限。
5. Web 的 xAddPhoneContact 返回 1008；xChooseContact 仅在支持 Contact Picker 的浏览器（多为 Android Chrome）可用。

版本

版权归 https://xui.tmui.design 你不得修改及二次开发，仅供 TMUI4 会员商用使用。不得转给非 VIP 会员使用，一经查实数倍赔偿，并追究法律责任。

更新日志

1.0.0（2026-08-16）

• 新增 xAddPhoneContact / xChooseContact，对齐微信通讯录能力与 DCloud success / fail / complete
• 支持 Android / iOS / HarmonyOS / Web / 微信小程序